From acf30ee10a84c8069fec2f37c97e1a84e62a38a5 Mon Sep 17 00:00:00 2001 From: justbur Date: Fri, 18 Sep 2015 13:19:48 -0400 Subject: [PATCH] Remove some alists from customize and update docs The helper functions should be used now due to the nature of the lists. Removing the variables from customize should encourage this. Also add automatic conversion of old format of `which-key-key-based-description-replacement-alist`. --- README.org | 38 +++++++++-------------- which-key.el | 88 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 69 insertions(+), 57 deletions(-) diff --git a/README.org b/README.org index ed9c48457fb..e8329347164 100644 --- a/README.org +++ b/README.org @@ -244,42 +244,34 @@ of behind each alist is that you specify a selection string in the =car= of each cons cell and the replacement string in the =cdr=. **** "Key-Based" replacement -The relevant variable is the awkwardly named -=which-key-key-based-description-replacement-alist= (Note on 3/9/2015 the -internal format of this list changed). In this alist you can have cons cells of -two types. An example of the first type is +[Note on 2015-9-3 the format of +=which-key-key-based-description-replacement-alist= changed. It will be easier +to use the functions below in your configuration, instead of modifying this +variable directly.] + +Using this method, the description of a key is replaced using a string that you +provide. Here's an example #+BEGIN_SRC Emacs-lisp -((listify-key-sequence (kbd "C-x C-f")) . "find files") +(which-key-add-key-based-replacements + "C-x C-f" "find files") #+END_SRC -where the string on the left is the key combination whose description you want -to replace, stored in a canonical form. For that key combination, which-key +where the first string is the key combination whose description you want to +replace, in a form suitable for =kbd=. For that key combination, which-key overwrites the description with the second string, "find files". In the second type of entry you can restrict the replacements to a major-mode. For example, #+BEGIN_SRC Emacs-lisp -(org-mode . (((listify-key-sequence (kbd "C-c C-c")) . "Org C-c C-c") - ((listify-key-sequence (kbd "C-c C-a")) . "Org Attach")) -#+END_SRC - -Here the first entry is the major-mode and the second is a list of the first -type of entries. In case the same key combination is listed under a major-mode -and by itself, the major-mode version will take precedence. - -To simplify adding these entries, there are two helper functions to add entries -to this list, =which-key-add-key-based-replacements= and -=which-key-add-major-mode-key-based-replacements=. With these functions the -above examples become - -#+BEGIN_SRC Emacs-lisp -(which-key-add-key-based-replacements - "C-x C-f" "find files") (which-key-add-major-mode-key-based-replacements 'org-mode "C-c C-c" "Org C-c C-c" "C-c C-a" "Org Attach") #+END_SRC +Here the first entry is the major-mode followed by a list of the first type of +entries. In case the same key combination is listed under a major-mode and by +itself, the major-mode version takes precedence. + **** Key and Description replacement The second and third methods target the text used for the keys and the diff --git a/which-key.el b/which-key.el index 95bdca90666..028a99629aa 100644 --- a/which-key.el +++ b/which-key.el @@ -104,21 +104,6 @@ This is a list of lists for replacing descriptions." :group 'which-key :type '(alist :key-type regexp :value-type string)) -(defcustom which-key-key-based-description-replacement-alist '() - "Each item in the list is a cons cell. -The car of each cons cell is either a string like \"C-c\", in -which case it's interpreted as a key sequence or a value of -`major-mode'. Here are two examples: - -(\"SPC f f\" . \"find files\") -(emacs-lisp-mode . ((\"SPC m d\" . \"debug\"))) - -In the first case the description of the key sequence \"SPC f f\" -is overwritten with \"find files\". The second case works the -same way using the alist matched when `major-mode' is -emacs-lisp-mode." - :group 'which-key) - (defcustom which-key-highlighted-command-list '() "A list of strings and/or cons cells used to highlight certain commands. If the element is a string, assume it is a regexp @@ -126,25 +111,7 @@ pattern for matching command names and use `which-key-highlighted-command-face' for any matching names. If the element is a cons cell, it should take the form (regexp . face to apply)." - :group 'which-key-key-based-description-replacement-alist) - -(defcustom which-key-prefix-name-alist '() - "An alist with elements of the form (key-sequence . prefix-name). -key-sequence is a sequence of the sort produced by applying `kbd' -then `listify-key-sequence' to create a canonical version of the -key sequence. prefix-name is a string." - :group 'which-key - :type '(alist :key-type string :value-type string)) - -(defcustom which-key-prefix-title-alist '() - "An alist with elements of the form (key-sequence . prefix-title). -key-sequence is a sequence of the sort produced by applying `kbd' -then `listify-key-sequence' to create a canonical version of the -key sequence. prefix-title is a string. The title is displayed -alongside the actual current key sequence when -`which-key-show-prefix' is set to either top or echo." - :group 'which-key - :type '(alist :key-type string :value-type string)) + :group 'which-key) (defcustom which-key-special-keys '("SPC" "TAB" "RET" "ESC" "DEL") "These keys will automatically be truncated to one character @@ -366,6 +333,28 @@ showing.") "Internal: Last location of side-window when two locations used.") +(defvar which-key-key-based-description-replacement-alist '() + "New version of +`which-key-key-based-description-replacement-alist'. Use +`which-key-add-key-based-replacements' or +`which-key-add-major-mode-key-based-replacements' to set this +variable.") + +(defvar which-key-prefix-name-alist '() + "An alist with elements of the form (key-sequence . prefix-name). +key-sequence is a sequence of the sort produced by applying `kbd' +then `listify-key-sequence' to create a canonical version of the +key sequence. prefix-name is a string.") + +(defvar which-key-prefix-title-alist '() + "An alist with elements of the form (key-sequence . prefix-title). +key-sequence is a sequence of the sort produced by applying `kbd' +then `listify-key-sequence' to create a canonical version of the +key sequence. prefix-title is a string. The title is displayed +alongside the actual current key sequence when +`which-key-show-prefix' is set to either top or echo.") + + ;;;###autoload (define-minor-mode which-key-mode "Toggle which-key-mode." @@ -408,6 +397,7 @@ set too high) and setup which-key buffer." (when (or (eq which-key-show-prefix 'echo) (eq which-key-popup-type 'minibuffer)) (which-key--setup-echo-keystrokes)) + (which-key--check-key-based-alist) (setq which-key--buffer (get-buffer-create which-key-buffer-name)) (with-current-buffer which-key--buffer ;; suppress confusing minibuffer message @@ -434,6 +424,36 @@ it's set too high)." ;; previous echo-keystrokes) ))) +(defun which-key--check-key-based-alist () + "Check (and fix if necessary) `which-key-key-based-description-replacement-alist'" + (let ((alist which-key-key-based-description-replacement-alist) + old-style res) + (dolist (cns alist) + (cond ((listp (car cns)) + (push cns res)) + ((stringp (car cns)) + (setq old-style t) + (push (cons (listify-key-sequence (kbd (car cns))) (cdr cns)) res)) + ((symbolp (car cns)) + (let (new-mode-alist) + (dolist (cns2 (cdr cns)) + (cond ((listp (car cns2)) + (push cns2 new-mode-alist)) + ((stringp (car cns2)) + (setq old-style t) + (push (cons (listify-key-sequence (kbd (car cns2))) (cdr cns2)) + new-mode-alist)))) + (push (cons (car cns) new-mode-alist) res))) + (t (message "which-key: there's a problem with the \ +entry %s in which-key-key-based-replacement-alist" cns)))) + (setq which-key-key-based-description-replacement-alist res) + (when old-style + (message "which-key: \ + `which-key-key-based-description-replacement-alist' has changed format and you\ + seem to be using the old format. Please use the functions \ +`which-key-add-key-based-replacements' and \ +`which-key-add-major-mode-key-based-replacements' instead.")))) + ;; Default configuration functions for use by users. Should be the "best" ;; configurations -- 2.30.2